home *** CD-ROM | disk | FTP | other *** search
/ 130 MIDI Tool Box / 130 MIDI Tool Box.iso / qb4midi / qbmidi.doc < prev    next >
Text File  |  1990-11-27  |  14KB  |  303 lines
  1.                           Q U I C K  B A S I C
  2.  
  3.                         ███ ███ █████ ████  █████
  4.                         █ █ █ █   █   █   █   █
  5.                         █  █  █   █   █   █   █
  6.                         █  █  █ █████ ████  █████ 
  7.  
  8.                        QBMIDI(TM) Library Overview
  9.  
  10.               S H A R E W A R E    V E R S I O N    1 . 0
  11.  
  12.                         SHAREWARE PRICE $20.00
  13.  
  14.                               Developed by:
  15.                       AskUs! Technology Specialists
  16.                                 PO Box 737
  17.                          Bountiful, UT 84011-0737
  18.  
  19.             QBMIDI is a Trademark of AskUs! Technology Specialists
  20.                    (c) 1990 AskUs.  All rights reserved.
  21.  
  22.  
  23. Hello and welcome to QBMIDI.  If you use MIDI and you program using
  24. Microsoft QuickBASIC or BASIC PDS, then we're confident you'll love the
  25. QBMIDI library, since it gives you to access and control your MIDI'ed
  26. instruments using simple QuickBASIC compatible calls.  QBMIDI V1.0 is a
  27. fully functional library of utilities that provide you with access to
  28. all of your MIDI instruments connected through a Roland MPU401 or
  29. compatible MIDI interface.  You can play your instruments via QuickBASIC
  30. as well as receive MIDI information and send MIDI commands to your MIDI'ed
  31. instruments.  It's simple, fast, and best of all ... you'll be in 
  32. control of your MIDI instruments! 
  33.  
  34. Included with this document file (QBMIDI.DOC), you'll find the following
  35. related files:
  36.  
  37.      QBM-DEM1.BAS     Initial demonstration program that features a few
  38.                       simple MIDI commands and general starting place
  39.                       to view source examples of QBMIDI's use.
  40.  
  41.      QBM-DEM2.BAS     A demonstration program that generates music based
  42.                       constraints you provide.  Not only does it show 
  43.                       working examples of your computer controlling your
  44.                       MIDI instruments, it's interesting to hear the
  45.                       sounds created.  We invite you to add functions and
  46.                       modify both of the demo programs to suit your needs.
  47.  
  48.      QBM-DEM3.BAS     A simple keyboard split program.
  49.  
  50.      QBMIDI.QLB       A QuickBASIC 4.5 environment QuickLibrary that
  51.                       provides you access to QBMIDI functions from within
  52.                       the QuickBASIC programming environment (QB.EXE).
  53.  
  54.      QBMIDI.LIB       A linkable library suitable for linking to your
  55.                       result .EXE programs.  Once linked, the QBMIDI calls
  56.                       you use become an integral part of your compiled 
  57.                       program.
  58.  
  59.      QBMIDI.ORD       Order information for the advanced MUSICIANS QBMIDI
  60.                       V2.0 which contains numerous advanced MIDI functions
  61.                       that are not included with this Shareware version.
  62.  
  63.  
  64. A QUICK OVERVIEW OF QBMIDI's V1.0 FUNCTIONS
  65. -------------------------------------------
  66.  
  67. CALL STATEMENT                 WHAT IT DOES
  68. --------------                 ---------------------------------------------
  69. CALL SeeIfMPUExists(Found)     If Midi Controller (MPU401) or compatible
  70.                                is found in your system 
  71. CALL ResetMpu                  Resets the MPU to power on state
  72. CALL SetDataInStopMode         Turns off some of the MPU's intelligence
  73.                                you'll be controlling it via QuickBASIC
  74. CALL PlayNote(Note, Velocity)  Plays a Note, striking it as you would from
  75.                                a keyboard with different strike velocities,
  76.                                or turns off a note currently playing
  77. CALL AllNotesOff               All notes off currently playing turned off
  78. CALL ChangePatchTo (NewPatch)  Change the patch (voice) currently in use
  79.                                to New Patch
  80. CALL ReceiveMidiData(Value)    Receive any midi data that may be coming
  81.                                in.  It listens to MIDI being sent back.
  82. CALL OmniModeOn                Turn on Omni, where all MIDI data will be
  83.                                played by all synthesizer channels.
  84. CALL OmniModeOff               Set Omni Off, where MIDI channel data is
  85.                                only received by the synthesizer's channel
  86. CALL SetToPolyMode             Set multi-voice mode
  87. CALL SetToMonoMode             Set to Mono-voice mode
  88.  
  89.  
  90.  
  91. The demo programs make use of all functions found in QBMIDI 1.0, and
  92. describe usage within the source code of the demo programs.  We encourage
  93. experimentation with the demo programs to gain a better understanding while
  94. having some fun.
  95.  
  96.  
  97. FOR NEW QUICKBASIC PROGRAMMERS
  98. ------------------------------
  99. For new programmers, like we were at one time,we've tried to aim our examples
  100. at your level.  QuickBASIC's library and sub functions can be somewhat tricky
  101. at first, so we've listed what you should type to get the libraries loaded 
  102. and running.  If you're a pro at QuickBASIC please excuse the lengthy 
  103. descriptions, as we want everyone to get to make music as fast as possible 
  104. with the least amount of problems.
  105.  
  106.  
  107. USING QBMIDI WITHIN THE QUICKBASIC PROGRAMMING ENVIRONMENT (QB.EXE)
  108. -------------------------------------------------------------------
  109. Two libraries are provided with QBMIDI, one called QBMIDI.QLB (the Quick
  110. Library) and QBMIDI.LIB (the Linkable library).  When working within the
  111. QuickBASIC programming environment (ie. using QB.EXE), you have the option
  112. to load a QuickLibrary at the time you start QB.EXE.  We make use of this
  113. feature to enables you to use all of QBMIDI call routines while debugging
  114. your programs.
  115.  
  116. To start QuickBASIC with QBMIDI library functions available you would type
  117. the following:
  118.  
  119.      QB /L QBMIDI <Enter>
  120.  
  121. Note: The file QBMIDI.QLB should be placed in the same directory with your
  122.       other QB library files (typically the same directory where the file
  123.       QB.EXE is found).  You may also start QB.EXE with QBMIDI by adding
  124.       the pathname where to find QBMIDI.QLB (ie. QB /L Pathname\QBMIDI)
  125.  
  126. If when starting QB.EXE you receive this error message:
  127.  
  128.      Cannot find file (QBMIDI.QLB). Input path:
  129.  
  130. you may type in a new path name, but we recommend control ^C and re-entering
  131. a correct pathname from startup.  By doing this now, you'll save time when
  132. compiling your programs to .EXE executable's.
  133.  
  134. If you are greeted with the Microsoft QuickBASIC environment, without seeing
  135. any error messages, you can assume that QBMIDI.QLB was loaded and its 
  136. functions are available.  For some reason QuickBASIC doesn't tell you what 
  137. library is loaded of if the load went OK so we just say no news is good news.
  138.  
  139.  
  140. WITHIN THE QUICKBASIC PROGRAMMING ENVIRONMENT
  141. ---------------------------------------------
  142.  
  143. To use any of the QBMIDI commands, you simply call the command as you would
  144. a local SUB function.  Don't worry if you don't know how to use SUB's since
  145. QBMIDI does not use the SUB capabilities, but is merely called like one.
  146. For example:
  147.  
  148.      Any good midi program should first check to see if an MPU401 controller
  149.      is present, connected, and ready for data.  To find out we use the
  150.      QBMIDI SeeIfMPUExists command.  The full QuickBASIC call syntax is:
  151.  
  152.      CALL SeeIfMPUExists(Found)    
  153.  
  154. When run, the QBMIDI.QLB library function named SeeIfMPUExists is called and
  155. returns a value in the variable called Found.  SeeIfMPUExists returns the
  156. value of zero (0) for no MPU found and -1 indicating an MPU was located.
  157.  
  158. NOTE: If you receive the message Subprogram Not Found, this indicates you've
  159. not loaded QB using the /L option.  See the examples above and restart QB.EXE.
  160.  
  161. Each QBMIDI command functions in this same way, with one exception. Some
  162. commands require that you set the variables values before calling.  For
  163. example:
  164.  
  165.      If playing a note, we us the PlayNote command with the following
  166.      syntax.
  167.      
  168.      Note=60                           'Middle C
  169.      Velocity = 64                     'Moderate strike velocity
  170.      CALL PlayNote (Note,Velocity)     'Use QBMIDI playnote to play
  171.  
  172. In the above example, the values were set before calling the routine.  The 
  173. following table lists the QBMIDI command and a quick description of how it 
  174. is used. 
  175.  
  176. CALL STATEMENT                 SEND/RETURNED
  177. --------------                 ---------------------------------------------
  178. CALL SeeIfMPUExists(Found)     Found = 0 if no MPU is found
  179.                                Found = -1 if MPU is found and ready
  180.  
  181. CALL ResetMpu                  Resets the MPU to power on state. No variable
  182.                                is given or returned. Use sparingly to reset
  183.                                MPU if another program modifies it.  This will
  184.                                not stop notes in play. Use AllNotesOff.
  185.  
  186. CALL SetDataInStopMode         Turns off some of the MPU's intelligence.
  187.                                No variable is sent or returned.
  188.  
  189. Note = n                       Note to play. Range 0 to 127 where 60=Middle C
  190. Velocity = n                   Strike velocity. Range 0 to 127 where 1=soft
  191.                                127=hardest, and 0= turn note off.
  192. CALL PlayNote(Note, Velocity)  Plays a Note, passes variables Note, Velocity
  193.                                To turn note off, pass note number with the
  194.                                velocity set at zero (0). Note and velocity
  195.                                variables are left unchanged after call.
  196.  
  197. CALL AllNotesOff               All notes off currently playing turned off.
  198.                                No variable is sent or returned.
  199.  
  200. NewPatch = n                   Patch number to change to, range 0 - 127
  201. CALL ChangePatchTo (NewPatch)  Change the patch (voice) currently in use
  202.                                to New Patch number given. NewPatch variable
  203.                                is left unchanged after the call.
  204.  
  205. CALL ReceiveMidiData(Value)    Receive any midi data that may be coming
  206.                                in from synthesizers or keyboards. Several
  207.                                midi bytes may be sent in succession, so
  208.                                your routines should be ready to catch all
  209.                                that are sent.  See QBM-DEM2.BAS for more.
  210.  
  211. CALL OmniModeOn                Turn on Omni, where all MIDI data will be
  212.                                played by all synthesizer channels. No 
  213.                                variables are passed or returned.
  214. CALL OmniModeOff               Set Omni Off, where MIDI channel data is
  215.                                only received by the synthesizer's channel. No 
  216.                                variables are passed or returned.
  217. CALL SetToPolyMode             Set multi-voice mode. No variables are passed
  218.                                or returned.
  219. CALL SetToMonoMode             Set to Mono-voice mode. No variables are 
  220.                                passed or returned.
  221.  
  222.  
  223. Call up the program titled QBM-DEM1.BAS by using the FILE OPEN command and
  224. view it's contents.  This demo program shows a few of the basics and
  225. illustrates how we call the routines from QuickBASIC.  
  226.  
  227.  
  228. COMPILING PROGRAMS FROM QUICKBASIC SO THEY CAN USE QBMIDI
  229. ---------------------------------------------------------
  230.  
  231. One nice feature within QuickBASIC is its ability to compile your program
  232. to a standalone or runtime .EXE file and use the library you started with.
  233. Since you started QB using the /L QBMIDI command, Quick-BASIC will 
  234. automatically use the QBMIDI.LIB (run version of QBMIDI) file when it 
  235. compiles your program.
  236.  
  237. To compile you're program, use Alt select, Run, Make EXE file.  Your screen
  238. should resemble the following.  Select Make EXE and Exit and QuickBASIC will
  239. compile your program and exit.  To run the example below after compile, you
  240. type QBM-DEM1 <Enter>.
  241.  
  242.   File  Edit  View  Search  <RUN>  Debug  Calls  Options            Help  
  243. ┌─────────────────────────────── Untitled ──────────────────────────┤├─┐
  244. │   ┌───────────────────────── Make EXE File ───────────────────────┐   
  245. │   │                ┌────────────────────────────────────────────┐ │   ░
  246. │   │ EXE File Name: │QBM-DEM1.EXE                                │ │   ░
  247. │   │                └────────────────────────────────────────────┘ │   ░
  248. │   │                                                               │   ░
  249. │   │   [ ] Produce Debug Code         Produce:                     │   ░
  250. │   │                                  ( ) EXE Requiring BRUN45.EXE │   ░
  251. │   │                                  (X) Stand-Alone EXE File     │   ░
  252. │   ├───────────────────────────────────────────────────────────────┤   ░
  253. │   │  < Make EXE >   < Make EXE and Exit >   < Cancel >   < Help > │   ░
  254. │   └───────────────────────────────────────────────────────────────┘   ░
  255. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  256.  
  257.  
  258. If you wish a further discussion of linking libraries, we refer you to your
  259. Microsoft documentation.
  260.  
  261.  
  262. PDS7 (BASIC 7.x) USERS
  263. ----------------------
  264. Please write us about receiving PDS7.x compatible versions of QBMIDI.QLB and
  265. QBMIDI.LIB.  We'll also supply QBMIDI.OBJ so you may add the functions to
  266. other libraries you have.
  267.  
  268.  
  269. CONCLUSION
  270. -----------
  271. We hope you, like us, enjoy making music and we feel making music with Quick-
  272. BASIC is more fun than writing any other type of program.  As you experiment
  273. you may find referring to the MIDI specification helpful or related MIDI
  274. books helpful in understanding what's going on.  
  275.  
  276. We also want you to know about our MUSICIANS VERSION of QBMIDI, that contains
  277. added features such as:
  278.  
  279. o  Independent receive and Transmit over all 16 midi channels
  280. o  Record and Playback using the MPU401
  281. o  Facilities for MIDI dumps, voice dumps, etc.
  282. o  Direct access to transmit and receive MIDI data
  283. o  Metronome On/Off
  284. o  Tempo adjustment
  285. o  Customization to your synth's features
  286. o  Superb Printed documentation
  287. o  And much more ...
  288.  
  289. You may order MUSICIANS QBMIDI V2.0 by sending $45.00 cash or
  290. check (we'll pay shipping to you by return mail) with your return address 
  291. info to:
  292.  
  293.      AskUs!
  294.      QBMIDI 2.0
  295.      PO Box 737
  296.      Bountiful, UT 84011-0737
  297.  
  298. We thank you for trying QBMIDI and hope you find making QB Music as
  299. enjoyable as we have.
  300.  
  301. Best Regards,
  302. AskUs!
  303.